/*
Copyright 2011 Johan Maasing

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
 */
package nu.zoom.gal.progress;

import javax.swing.JProgressBar;

import nu.zoom.swing.desktop.PlugIn;
import nu.zoom.swing.desktop.worker.EventQueuePolicy;
import nu.zoom.swing.desktop.worker.Policy;

/**
 * Used to show the user progress for background tasks. To use first create a
 * taskID, then use the JProgress-like methods to indicate progress. When the
 * task finishes please call the delete method.
 * 
 * @author "Johan Maasing" &lt;johan@zoom.nu&gt;
 * 
 */
public interface Progress extends PlugIn {
	/**
	 * Create a new task.
	 * 
	 * @return The task identification.
	 */
	public TaskID createTask();

	/**
	 * The task is finished and no more progress will be reported on this task.
	 * 
	 * @param taskID
	 *            The identification of the task. May not be null.
	 */
	public void deleteTask(TaskID taskID);

	/**
	 * Set the status of the task to be of indeterminate length.
	 * 
	 * @param taskID
	 *            The identification of the task. May not be null. If the taskID
	 *            is unknown or deleted this method does nothing.
	 * @param True
	 *            if the progress should be shown as indeterminate.
	 * @see JProgressBar#setIndeterminate(boolean)
	 */
	@EventQueuePolicy(Policy.EVENT_QUEUE)
	public void setIndeterminate(TaskID taskID, boolean value);

	/**
	 * Set the maximum value that the progress of this task will reach.
	 * 
	 * @param taskID
	 *            The identification of the task. May not be null. If the taskID
	 *            is unknown or deleted this method does nothing.
	 * @param max
	 *            The maximum value to set for the progressbar.
	 * @see JProgressBar#setValue(int)
	 */
	@EventQueuePolicy(Policy.EVENT_QUEUE)
	public void setMaximum(TaskID taskID, int max);

	/**
	 * Set the minimum value that the progress of this task use.
	 * 
	 * @param taskID
	 *            The identification of the task. May not be null. If the taskID
	 *            is unknown or deleted this method does nothing.
	 * @param min
	 *            The maximum value to set for the progressbar.
	 * @see JProgressBar#setMinimum(int)
	 */
	@EventQueuePolicy(Policy.EVENT_QUEUE)
	public void setMinimum(TaskID taskID, int min);

	/**
	 * Report progress of the given task.
	 * 
	 * @param taskID
	 *            The identification of the task. May not be null. If the taskID
	 *            is unknown or deleted this method does nothing.
	 * @param value
	 *            The value to set to indicate progress towards maximum.
	 * @see JProgressBar#setValue(int)
	 */
	@EventQueuePolicy(Policy.EVENT_QUEUE)
	public void setValue(TaskID taskID, int value);

	/**
	 * Set an informational message explaining what the task is doing.
	 * 
	 * @param taskID
	 *            The identification of the task. May not be null. If the taskID
	 *            is unknown or deleted this method does nothing.
	 * @param message
	 *            The message to set. If null any previous message for the task
	 *            will be removed.
	 */
	public void setMessage(TaskID taskID, CharSequence message);

	public interface TaskID {
	}
}
